/*
 * 2005-12-26 lxm 创建。 
 */
package com.hd123.rumba.organization;

import net.sf.hibernate.HibernateException;

import com.hd123.rumba.exception.BusinessException;
import com.hd123.rumba.runtime.IManager;
import com.hd123.rumba.runtime.OperateContext;
import com.hd123.rumba.util.ClassifiedHashtable;

/**
 * 组织角色 | 管理员 | 接口类
 * <p>
 * 
 * 针对抽象接口类IOrgRole的管理员对象，也是抽象的。要求<code>IOrgRole</code>的子类对应的管理员<br>
 * 必须由本对象派生，并在实现类中实现其中的方法。
 * 
 * @author lxm
 * 
 */
public interface IOrgRoleMgr extends IManager {

  /**
   * 新建一个组织角色。
   * <p>
   * 
   * 若指定组织已经包含一个相同类型的组织角色，无论其状态是否是VALUE_STATE_DELETED，则不会创建<br>
   * 一个新的组织角色，而是直接将其返回；否则创建一个新的组织角色。
   *  
   * @param organization
   *          组织角色所修饰的组织。
   * @return
   * @throws BusinessException
   */
  public IOrgRole createOrgRole(IOrganization organization) throws BusinessException;

  /**
   * 组织角色的合法性检查。
   * <p>
   * 
   * 不做oca检查。提供给IOrganizationMgr调用。
   * 
   * @param orgRole
   *          被检查的组织角色
   * @param withWarn
   * @return
   * @throws BusinessException
   */
  public ClassifiedHashtable verifyOrgRole(IOrgRole orgRole, boolean withWarn)
      throws BusinessException, HibernateException;

  /**
   * 当对应组织被保存前触发的事件响应。
   * 
   * @param orgRole
   *          被保存组织中的组织角色。
   * @param operate
   * @throws BusinessException
   * @throws HibernateException
   */
  public void onBeforeSaveOrg(IOrgRole orgRole, OperateContext operate)
      throws BusinessException, HibernateException;

  /**
   * 当对应组织被保存后触发的事件响应。
   * 
   * @param orgRole
   *          被保存组织中的组织角色。
   * @param operate
   * @throws BusinessException
   * @throws HibernateException
   */
  public void onAfterSaveOrg(IOrgRole orgRole, OperateContext operate)
      throws BusinessException, HibernateException;

  /**
   * 当对应组织被删除前触发的事件响应。
   * 
   * @param orgRole
   *          被删除组织中的组织角色。
   * @param operate
   * @throws BusinessException
   * @throws HibernateException
   */
  public void onDeleteOrg(IOrgRole orgRole, OperateContext operate)
      throws BusinessException, HibernateException;

  /**
   * 当对应组织被恢复删除前触发的事件响应。
   * 
   * @param orgRole
   *          被恢复删除组织中的组织角色。
   * @param operate
   * @throws BusinessException
   * @throws HibernateException
   */
  public void onUndeleteOrg(IOrgRole orgRole, OperateContext operate)
      throws BusinessException, HibernateException;

  /**
   * 当对应组织被物理删除前触发的事件响应。
   * 
   * @param orgRole
   *          被物理删除组织中的组织角色。
   * @throws BusinessException
   * @throws HibernateException
   */
  public void onBeforeRemoveOrg(IOrgRole orgRole) throws BusinessException, HibernateException;

  /**
   * 当指定组织角色被添加到指定的组织中时被触发的事件响应。
   * 
   * @param organization
   *          被修改的组织
   * @param orgRole
   *          被添加的组织角色。
   * @return 若返回null，表示允许添加；反之则表示禁止将该组织角色添加到指定的组织中。
   * @throws BusinessException
   * @throws HibernateException
   */
  public ClassifiedHashtable onBeforeAddOrgRole(IOrganization organization, IOrgRole orgRole)
      throws BusinessException, HibernateException;

  /**
   * 当指定组织角色从指定的组织中被物理删除时触发的事件响应。
   * <p>
   * 
   * @param organization
   *          被修改的组织。
   * @param orgRole
   *          被删除的组织角色。
   * @return 若返回null，表示允许删除；反之则表示禁止将该组织角色从指定的组织中删除。
   * @throws BusinessException
   * @throws HibernateException
   */
  public ClassifiedHashtable onBeforeRemoveOrgRole(IOrganization organization, IOrgRole orgRole)
      throws BusinessException, HibernateException;

  /**
   * 改变指定组织角色的状态。
   * <p>
   * 
   * 提供给表示层程序调用。调用前应先通过调用<code>IOrganization.saveOrganization</code>保存对应的组织。
   * 
   * @param orgRole
   *          被修改的组织角色。
   * @param toState
   *          组织角色目标状态。
   * @param operate
   * @param oca
   *          参数orgRole的共享校验标志。
   * @throws BusinessException
   * @throws HibernateException
   */
  public void changeOrgRole(IOrgRole orgRole, Integer toState, OperateContext operate, long oca)
      throws BusinessException, HibernateException;

  /**
   * 判断指定的组织角色实例是否是本管理员对象对应的实体对象。
   * 
   * @param orgRole
   *          被判断的组织角色实例。
   * @return
   */
  public boolean canManage(IOrgRole orgRole);
  
  /**
   * 取得对应组织角色的标题。
   * 
   * @return 组织角色的CAPTION_CLASS。
   */
  public String getOrgRoleCaption();
}
